Claude API 총정리

# Python SDK 설치
pip install anthropic

# TypeScript/Node.js SDK 설치
npm install @anthropic-ai/sdk

# Linux / macOS
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx..."

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "sk-ant-api03-xxxxx..."

import anthropic

client = anthropic.Anthropic()  # 환경변수에서 API 키 자동 로드

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "안녕하세요! Claude API를 처음 사용해 봅니다."}
    ]
)

print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // 환경변수에서 API 키 자동 로드

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "안녕하세요! Claude API를 처음 사용해 봅니다." }
  ],
});

console.log(message.content[0].text);

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "system": "당신은 친절한 한국어 도우미입니다.",
  "messages": [
    {"role": "user", "content": "파이썬으로 피보나치 수열을 구하는 함수를 짜줘."}
  ],
  "temperature": 0.7,
  "top_p": 0.9
}

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "다음은 파이썬으로 작성한 피보나치 수열 함수입니다..."
    }
  ],
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 256
  }
}

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system="당신은 파이썬 전문가입니다.",
    messages=[
        # 1턴: 사용자 질문
        {"role": "user", "content": "파이썬에서 리스트와 튜플의 차이는?"},
        # 1턴: Claude 응답 (이전 응답을 그대로 넣음)
        {"role": "assistant", "content": "리스트는 수정 가능(mutable)하고..."},
        # 2턴: 후속 질문
        {"role": "user", "content": "그렇다면 언제 튜플을 써야 하나요?"}
    ]
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    system="""당신은 시니어 백엔드 개발자입니다.
규칙:
- 한국어로 답변합니다.
- 코드에는 항상 주석을 포함합니다.
- 보안 취약점이 있으면 반드시 경고합니다.
- 응답은 간결하고 실용적으로 합니다.""",
    messages=[
        {"role": "user", "content": "Node.js에서 JWT 인증을 구현하는 방법을 알려줘."}
    ]
)

import anthropic

client = anthropic.Anthropic()

# 방법 1: with 문 사용 (권장)
with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[
        {"role": "user", "content": "양자 컴퓨팅의 원리를 설명해줘."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

print()  # 줄바꿈

# 방법 2: 이벤트 기반 처리
with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[
        {"role": "user", "content": "양자 컴퓨팅의 원리를 설명해줘."}
    ]
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const stream = client.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 2048,
  messages: [
    { role: "user", content: "양자 컴퓨팅의 원리를 설명해줘." }
  ],
});

// 텍스트만 간단히 출력
stream.on("text", (text) => {
  process.stdout.write(text);
});

// 완료 후 최종 메시지 확인
const finalMessage = await stream.finalMessage();
console.log("\n\nTotal tokens:", finalMessage.usage);

import anthropic
import base64

client = anthropic.Anthropic()

# 이미지 파일을 Base64로 변환
with open("chart.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "이 차트의 핵심 트렌드를 분석해 주세요."
                }
            ]
        }
    ]
)

print(response.content[0].text)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://example.com/dashboard-screenshot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "이 대시보드에서 매출이 가장 높은 달은?"
                }
            ]
        }
    ]
)

import anthropic

client = anthropic.Anthropic()

# 도구(함수) 정의
tools = [
    {
        "name": "get_weather",
        "description": "지정된 도시의 현재 날씨 정보를 반환합니다.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "날씨를 조회할 도시 이름 (예: 서울, Tokyo)"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "온도 단위"
                }
            },
            "required": ["city"]
        }
    }
]

# 1단계: Claude에게 요청
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "서울 날씨 어때?"}
    ]
)

# 2단계: Claude가 도구 호출을 요청하면 처리
if response.stop_reason == "tool_use":
    tool_block = next(b for b in response.content if b.type == "tool_use")
    
    print(f"호출할 도구: {tool_block.name}")
    print(f"인자: {tool_block.input}")
    # → 호출할 도구: get_weather
    # → 인자: {"city": "서울", "unit": "celsius"}
    
    # 3단계: 실제 함수 실행 (여기서는 가상 결과)
    weather_result = {"temperature": 22, "condition": "맑음", "humidity": 45}
    
    # 4단계: 결과를 Claude에게 전달
    final_response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=[
            {"role": "user", "content": "서울 날씨 어때?"},
            {"role": "assistant", "content": response.content},
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": tool_block.id,
                        "content": str(weather_result)
                    }
                ]
            }
        ]
    )
    
    print(final_response.content[0].text)
    # → "서울의 현재 날씨는 맑고, 기온은 22°C이며 습도는 45%입니다."

# 웹 검색 도구 사용 (Anthropic이 실행을 처리)
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    tools=[{"type": "web_search_20260209"}],
    messages=[
        {"role": "user", "content": "오늘 한국 주식시장 상황을 알려줘."}
    ]
)

# 서버 도구는 별도 실행 없이 바로 결과 포함
print(response.content[-1].text)

import anthropic

client = anthropic.Anthropic()

# Sonnet 4.6에서 Extended Thinking 사용
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "n mod 4 == 3인 소수가 무한히 많은지 증명해줘."
        }
    ]
)

# 응답에서 thinking과 text 블록을 구분
for block in response.content:
    if block.type == "thinking":
        print(f"[사고 과정 요약]\n{block.thinking}\n")
    elif block.type == "text":
        print(f"[최종 답변]\n{block.text}")

# Opus 4.7은 adaptive thinking + effort를 사용
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},  # budget_tokens 대신 adaptive
    messages=[
        {
            "role": "user",
            "content": "다음 시스템의 보안 취약점을 분석하고 개선 방안을 제시해줘..."
        }
    ]
)

import anthropic

client = anthropic.Anthropic()

# 긴 시스템 프롬프트 + 문서를 캐싱
long_document = "..." * 10000  # 매우 긴 문서

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": "당신은 법률 문서 분석 전문가입니다.",
        },
        {
            "type": "text",
            "text": f"다음은 분석할 계약서입니다:\n\n{long_document}",
            "cache_control": {"type": "ephemeral"}  # 이 부분을 캐시
        }
    ],
    messages=[
        {"role": "user", "content": "이 계약서에서 위약금 조항을 찾아줘."}
    ]
)

# 응답의 usage에서 캐시 상태 확인
print(f"캐시 생성 토큰: {response.usage.cache_creation_input_tokens}")
print(f"캐시 읽기 토큰: {response.usage.cache_read_input_tokens}")
print(f"일반 입력 토큰: {response.usage.input_tokens}")

import anthropic
import time

client = anthropic.Anthropic()

def call_with_retry(messages, max_retries=5):
    """지수 백오프를 적용한 재시도 로직"""
    for attempt in range(max_retries):
        try:
            response = client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                messages=messages
            )
            return response
        except anthropic.RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt  # 1, 2, 4, 8, 16초
            print(f"Rate limit 도달. {wait_time}초 후 재시도...")
            time.sleep(wait_time)
    return None

import anthropic

client = anthropic.Anthropic()

SYSTEM_PROMPT = """당신은 '테크마트' 온라인 쇼핑몰의 고객 지원 AI입니다.

규칙:
1. 항상 친절하고 공손한 한국어로 답변합니다.
2. 환불/교환 문의 시 주문번호를 먼저 확인합니다.
3. 모르는 내용은 "상담원 연결"을 안내합니다.
4. 개인정보(카드번호, 비밀번호 등)는 절대 요청하지 않습니다.

상품 정보:
- 배송: 결제 후 1-3 영업일
- 교환/환불: 수령 후 7일 이내
- 고객센터: 1588-0000 (평일 9-18시)"""

def chat(conversation_history: list, user_message: str) -> str:
    """대화 이력을 유지하며 응답 생성"""
    conversation_history.append(
        {"role": "user", "content": user_message}
    )
    
    response = client.messages.create(
        model="claude-haiku-4-5-20251001",  # 빠른 응답 위해 Haiku
        max_tokens=512,
        system=SYSTEM_PROMPT,
        messages=conversation_history
    )
    
    assistant_message = response.content[0].text
    conversation_history.append(
        {"role": "assistant", "content": assistant_message}
    )
    
    return assistant_message

# 사용 예시
history = []
print(chat(history, "배송은 얼마나 걸려요?"))
print(chat(history, "교환하고 싶은데 어떻게 해야 하나요?"))

import anthropic
import json

client = anthropic.Anthropic()

# Tool을 사용한 구조화된 출력 (Structured Outputs)
tools = [
    {
        "name": "extract_receipt",
        "description": "영수증에서 정보를 추출합니다.",
        "input_schema": {
            "type": "object",
            "properties": {
                "store_name": {"type": "string", "description": "매장명"},
                "date": {"type": "string", "description": "구매일 (YYYY-MM-DD)"},
                "items": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": {"type": "string"},
                            "quantity": {"type": "integer"},
                            "price": {"type": "number"}
                        },
                        "required": ["name", "quantity", "price"]
                    }
                },
                "total": {"type": "number", "description": "총 결제 금액"}
            },
            "required": ["store_name", "date", "items", "total"]
        }
    }
]

receipt_text = """
마트24 강남점
2024-12-15
우유 1L x2  3,400원
식빵     x1  2,800원
계란 30구 x1  6,900원
합계: 13,100원
"""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "extract_receipt"},
    messages=[
        {"role": "user", "content": f"다음 영수증에서 정보를 추출해줘:\n{receipt_text}"}
    ]
)

# 구조화된 JSON 결과
result = response.content[0].input
print(json.dumps(result, ensure_ascii=False, indent=2))

# =============================================
# Claude API 치트시트 - 핵심 패턴 모음
# =============================================

import anthropic
client = anthropic.Anthropic()

# ── 1. 기본 호출 ──
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

# ── 2. 시스템 프롬프트 ──
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="당신은 한국어 번역가입니다.",
    messages=[{"role": "user", "content": "Translate: Hello World"}]
)

# ── 3. 스트리밍 ──
with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "긴 이야기를 해줘."}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# ── 4. 이미지 입력 (URL) ──
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "url", "url": "https://..."}},
            {"type": "text", "text": "이 이미지를 설명해줘."}
        ]
    }]
)

# ── 5. Tool Use ──
tools = [{"name": "calc", "description": "계산기",
          "input_schema": {"type": "object",
                           "properties": {"expression": {"type": "string"}},
                           "required": ["expression"]}}]
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "2^10 계산해줘"}]
)

# ── 6. Extended Thinking ──
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "복잡한 문제..."}]
)

# ── 7. 프롬프트 캐싱 ──
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "매우 긴 시스템 프롬프트...",
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": "질문"}]
)

# ── 8. Batch API ──
batch = client.messages.batches.create(
    requests=[
        {"custom_id": "req-1",
         "params": {"model": "claude-sonnet-4-6",
                    "max_tokens": 1024,
                    "messages": [{"role": "user", "content": "질문1"}]}},
        {"custom_id": "req-2",
         "params": {"model": "claude-sonnet-4-6",
                    "max_tokens": 1024,
                    "messages": [{"role": "user", "content": "질문2"}]}}
    ]
)

# ── 9. 토큰 카운팅 ──
count = client.messages.count_tokens(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(f"입력 토큰: {count.input_tokens}")

# ── 10. Web Search (서버 도구) ──
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    tools=[{"type": "web_search_20260209"}],
    messages=[{"role": "user", "content": "최신 뉴스 검색해줘"}]
)